GREENLOOP v2.4.0 · workflow for coding agents · MIT
GREENLOOP is a state-machine execution workflow you hand to any AI coding agent: Claude Code, Cursor, Windsurf, Aider, local models. It makes the agent persist its state, converge before it edits, test its own assumptions, and refuse to call anything finished until a verification harness says so.
$ curl -fsSL https://greenloop.violhex.workers.dev/install.sh | sh
Inject this repo only, no CLI: … | sh -s -- --repo
· both: --all · remove: --uninstall
Why it exists
They're process failures: the agent forgets what it decided, keeps expanding options instead of committing to one, or executes a plan built on an assumption nobody tested. GREENLOOP installs three disciplines against exactly those three failures. Every rule scales with the task, so a typo fix runs a compressed pass while destructive work gets full ceremony plus your confirmation.
Every decision, assumption, failure, and verification result is persisted to
.greenloop/: state, plan, memory, worklog. If it exists only in
context, it does not exist. Sessions resume from disk, not recollection.
kills: context loss, amnesia between sessions
Three cognitive states: ORBITING → CONTACT → LOCK_IN. No edit or irreversible
action until the agent can write a falsifiable DONE WHEN. Branch
pressure checks force a choice when options multiply without progress.
kills: orbiting, premature execution
Assumptions live in a market, each with confidence, evidence, and a falsifier. The load-bearing one gets tested first. Beliefs expire. The DoD is checked against your original words, so the goal can't quietly drift.
kills: confidently wrong, goal corruption
Quickstart
Run the curl above. It fetches the workflow files, verifies checksums, and
installs a greenloop command (runs on Bun,
falls back to npx).
Run greenloop inside any repo. It detects which agents you use and
writes each one's native binding: CLAUDE.md import plus enforcement
hooks, .cursor/rules, AGENTS.md, sixteen targets in all.
Re-running upgrades in place; existing files are merged or backed up, never clobbered.
Phase 1 initializes .greenloop/ and the loop runs until the
harness exits 0. The worklog is your audit trail.
repo/ ├── GREENLOOP.md the workflow: contract, S/C/R, phases 0–10 ├── GREENLOOP-APPENDICES.md orchestration, no-tools mode, role library ├── greenloop.state.schema.json copy to .greenloop/state.json to start ├── GREENLOOP-PROFILE-DESIGN.md domain profile, activates on visual tasks ├── AGENTS.md universal binding (marker block) └── .greenloop/ state · plan · memory · worklog
Inventory
Each target gets its native instruction channel. Anything not listed
still reads the universal AGENTS.md binding.
Enforcement
On Claude Code, GREENLOOP optionally installs two gates that don't depend on the model's obedience at all:
PreToolUse gate: file edits are blocked until
.greenloop/state.json exists, so Phase 1 can't be skipped.
Stop gate: the session can't end while
scripts/verify.sh exits non-zero. "Continue till green" becomes a
property of the system, not a hope.
GREEN = every Definition-of-Done item satisfied AND every harness check passes AND no known unresolved error remains in scope. Mechanically verifiable: "looks correct" is never GREEN.
An example run
Field test · no install, no tools
GREENLOOP is instructions, not software, so its minimum viable
deployment is paste. This condensed transcript comes from exactly that:
GREENLOOP.md dropped into a plain ChatGPT tab with a web-design idea.
No injection, no hooks, no tools. The workflow still governed the session:
“Here's GREENLOOP.md. I want a site with the delivery and feel of a high-end Framer site (animated icons, motion, clean typography), and it should take style changes that equally match.”
Refused to copy pixels. Reconstructed the upper layers first, the constraints that caused the reference to emerge, and returned the chain as the deliverable:
artifact → structure → rules → constraints → intent
├ tokens.json scales inferred, not pixels copied
├ motion-spec.md reveal: y 24→0 · 600ms · stagger 80ms
├ component-spec.md shared rules = evidence of a system
└ brand-spec.md the feeling + what was deliberately NOT done
“No component may be implemented until the visual, motion, interaction, and emotional systems it expresses are explicitly described.” That is GREENLOOP's no execution from ORBITING, wearing design clothes. The constitution it wrote is the spec you carry to whichever agent builds it.
That session is now a shipped companion: GREENLOOP-PROFILE-DESIGN.md, the first domain profile. Five-level extraction (visual → component → motion → emotional → contradiction), the design constitution, judges with motion-language and accessibility lenses, and a falsifiable design GREEN. Drop it next to GREENLOOP.md; it activates when the task is visual.
Get the files
Everything is markdown, JSON, and one TypeScript file. Read them before you run them. That's the point.
Only when the task earns it. Phase 1 classifies every task as TRIVIAL, STANDARD, COMPLEX, or HAZARDOUS, and the workflow compresses to match: a typo fix collapses the review gates into a 30-second self-check, while destructive or security-relevant work runs everything plus an explicit confirmation from you. Effort is also budgeted up front; crossing 75% of a budget forces a compressed mode instead of letting the agent polish forever. The ceremony is a dial, not a constant.
Yes, by construction. Shared files (CLAUDE.md, AGENTS.md,
settings) get a marker-delimited block; your content is untouched. Files GREENLOOP
doesn't recognize are backed up to .bak before replacement. Nothing is
ever deleted, and re-running is a no-op until a new version ships.
Bun for the full TUI (auto-installs its one
dependency), or npx as a fallback. The --repo install mode needs
nothing but sh and curl; it's how you bring GREENLOOP to a CI box
or a bare container.
Please do. GREENLOOP.md is the single source of truth. Edit it,
version it with your repo, and your agents pick up the change on their next run.
Fork the whole site, point install.sh at your domain, and you've
shipped your team's edition.
… | sh -s -- --uninstall removes the CLI and
~/.greenloop. Per-repo files are left for you to delete; they're
your audit trail.